/**
 * Copyright (c) 2007, Blue Hole Software. All rights reserved.
 * Code licensed under the Apache 2.0 License:
 * http://www.apache.org/licenses/
 */
package org.bhf.email;

import javax.mail.Session;
import javax.mail.Message;
import javax.mail.MessagingException;

/**
 * Facility to return configured email Sessions for sending email. For example, you can send email using the following
 * code snippit.
 * <code><pre>
 *       final eMailFacility mail    = Facilities.get( eMailFacility.class );
 *       final Session       session = mail.getSession();
 *       final MimeMessage   message = new MimeMessage( session );
 *
 *       message.setFrom( new InternetAddress( "joe@bluehole.com" ) );
 *       message.addRecipient( Message.RecipientType.TO, new InternetAddress( "bob@acme.com" ) );
 *       message.setSubject( "aSubject" );
 *       message.setText( "Really important stuff" );
 *
 *       mail.transportSend( session, message );
 * </code></pre>
 */
public interface eMailFacility
{
    /**
     * Return a configured email Sesion for sending email.
     * @return a configured email Sesion for sending email.
     */
    Session getSession();

    /**
     * You MUST use this method instead of Transport.send() if you are using SSL
     * @param session Session return from <code>getSession()</code>.
     * @param message Message to send
     * @throws MessagingException Error sending the message
     */
    void    transportSend( final Session session, final Message message )
        throws MessagingException;
}
